using System;

namespace NFreeMarker.Template
{
    /**
     * An interface that can be implemented by writers returned from
     * {@link TemplateTransformModel#getWriter(java.io.Writer, java.util.Map)}. The
     * methods on this
     * interfaces are callbacks that will be called by the template engine and that
     * give the writer a chance to better control the evaluation of the transform
     * body. The writer can instruct the engine to skip or to repeat body 
     * evaluation, and gets notified about exceptions that are thrown during the
     * body evaluation.
     *
     * @author Attila Szegedi
     * @version $Id: TransformControl.java,v 1.11 2005/06/16 18:13:58 ddekany Exp $
     */

    public interface ITransformControl
    {
        /**
         * Called before the body is evaluated for the first time.
         * @return 
         * <ul>
         * <li><tt>SkipBody</tt> if the transform wants to ignore the body. In this
         * case, only {@link java.io.Writer#close()} is called next and processing ends.</li>
         * <li><tt>EvaluateBody</tt> to normally evaluate the body of the transform
         * and feed it to the writer</li>
         * </ul>
         */
        int OnStart();

        /**
         * Called after the body has been evaluated.
         * @return
         * <ul>
         * <li><tt>EndEvaluation</tt> if the transformation should be ended.</li>
         * <li><tt>RepeatEvaluation</tt> to have the engine re-evaluate the 
         * transform body and feed it again to the writer.</li>
         * </ul>
         */
        int AfterBody();

        /**
         * Called if any exception occurs during the transform between the
         * {@link TemplateTransformModel#getWriter(java.io.Writer, java.util.Map)} call
         * and the {@link java.io.Writer#close()} call.
         * @param t the throwable that represents the exception. It can be any 
         * non-checked throwable, as well as {@link TemplateException} and 
         * {@link java.io.IOException}.
         * 
         * @throws Throwable is recommended that the methods rethrow the received 
         * throwable. If the method wants to throw another throwable, it should
         * either throw a non-checked throwable, or an instance of 
         * {@link TemplateException} and {@link java.io.IOException}. Throwing any
         * other checked exception will cause the engine to rethrow it as
         * a {@link java.lang.reflect.UndeclaredThrowableException}.
         */
        void OnError(Exception e);
    }
}